<h1>Super Stack!</h1>

<p>Version 1 - Sun March 18th, 2012</p>

<p>by <a href="http://www.nickober.net">Nick Ober</a></p>

<h2>Intro</h2>

<p><em>Super Stack!</em> is an esoteric programming language that answers the question 
"What would it be like to program only using a single stack?"</p>

<h2>Programming in Super Stack!</h2>

<h3>Syntax</h3>

<p>The syntax of Super Stack! is simple.  Every command is a keyword.  The program 
is run command by command modifying a single stack for all data storage.  This 
leads to expressions being expressed in 
<a href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">postfix notation</a>.  Here 
is a simple program that adds two number, then outputs the result.</p>

<p>Example:  </p>

<pre><code>2 3 add output
</code></pre>

<p>Each number encountered is pushed onto the stack.  After 2 and 3 the stack 
looks like this: <code>[2, 3]</code> (note: when a stack is typed out like this, the 
bottom is to the left.)</p>

<p>When <code>add</code> is encountered, 2 and 3 are added together </p>

<h3>Using ss.py</h3>

<p>ss.py is a command line tool.  Give it a file as an argument and it will 
interpret it.  Alternatively, you can feed it <code>-i</code> or <code>--interactive</code> to run 
it in interactive mode, which gives you a way to test commands out and see 
immidiate results.  You can also use <code>-c</code> to compile the program under linux 
if gcc is installed.  <code>-o</code> defines an output file which defaults to <code>a.out</code>.</p>

<h2>The Preprocessor</h2>

<p><em>Super Stack!</em> uses a preprocessor to help the programmer define macros before 
runtime, include code written in other files, and write comments to help with 
code clarity.  It is heavily based on C's preprocessor, and should be very 
familier to C programmers.</p>

<h3>Strings</h3>

<p>Before running, Super Stack! will scan for characters in quotes.  When found,
the string is replaced inplace with the ascii values of characters placed in
reverse.</p>

<p>Example:</p>

<pre><code>"Hello, World!\n"
</code></pre>

<p>gets replaced as:</p>

<pre><code>33 100 108 114 111 87 32 44 111 108 108 101 72
</code></pre>

<p>Here's the numbers with thier ascii character equivelents below it:</p>

<pre><code>10 33 100 108 114 111 87 32 44 111 108 108 101 72
\n !  d   l   o   r   W     ,  o   l   l   e   H
</code></pre>

<p>Escape characters can also be used such as <code>\n</code> and <code>\t</code>.</p>

<h3>Macros</h3>

<p>Macros are defined using the <code>#define</code> directive.  Here is the syntax:</p>

<pre><code>#define [macroname] [commands]
</code></pre>

<p>Before runtime, all instances of <code>[macroname]</code> will be replace by <code>[commands]</code>.</p>

<p>Example usage:</p>

<pre><code>#define poptwo pop pop

1 2 poptwo
</code></pre>

<h3>Includes</h3>

<p>Includes insert the entire contents of one file into another.  Using the
<code>#include</code> directive, you can specify a file to insert into your code.  </p>

<p>Filenames should always use unix path names (the forward slash <code>/</code>) to refer to 
directories.  Paths will automaticly be converted properly depending on the 
host os.  </p>

<p>Example:
    /* contents of a.ss */
    #define numbers 3 2 1</p>

<pre><code>/* contents of b.ss */
#include a.ss
numbers output output output
</code></pre>

<p>When b.ss is run, 3 2 and 1 will be pushed onto the stack as defined in 
<code>a.ss</code>.  </p>

<p>If you wrap the filename in carrets (<code>&lt;</code> and <code>&gt;</code>), you include files found in 
the Super Stack! libraries, found in <code>tools/lib/</code>.</p>

<p>Example:</p>

<pre><code>#include &lt;io.ss&gt;
0 "Hello!" outputstring
</code></pre>

<p>This snippit uses a macro called <code>outputstring</code> found in <code>tools/lib/io.ss</code>.</p>

<h3>Comments</h3>

<p>Comments come in two flavors.  Single line and block.</p>

<p>Single line uses a double slash (<code>//</code>).  Everything after the slash is ignored
by the interpreter/compiler.</p>

<p>Example:    </p>

<pre><code>pop pop   // pop the top two numbers off the stack
</code></pre>

<p>Block quotes use the two symbols <code>/*</code> and <code>*/</code>.  Everything inbetween a pair
of these will be ignored.</p>

<p>Example:</p>

<pre><code>/*
   Program by John Smith
*/

1 2 add output
</code></pre>

<h2>Reference</h2>

<h3>Command Reference</h3>

<pre><code>123     Push the number 123 onto the stack.  You can use any positive or
        negative number.
</code></pre>

<h4>Math</h4>

<pre><code>add     Pop the top two numbers, push the sum of them.
sub     Pop the top two numbers, push the difference of them.
div     Pop the top two numbers, push the remainder of them.
mul     Pop the top two numbers, push the product of them.
mod     Pop the top two numbers, push the remainder of the  of them.
</code></pre>

<h4>Stack Manipulation</h4>

<pre><code>pop     Pop the top number of the stack and discard it.
swap    Swap the top two elements of the stack.
cycle   Move the top element to the bottom of the stack.
rcycle  Move the bottom element of the top.
dup     Duplicate the top number on the stack and push it.
clear   Clear all numbers from the stack and leave it empty.
</code></pre>

<h4>Flow</h4>

<pre><code>while   Start a while loop.  If the top of the stack is 0, skip to matching
        wend.  Otherwise enter the loop.
wend    End while loop.  If the top of the stack is non zero
</code></pre>

<h4>Logic</h4>

<pre><code>and     Pop the top two numbers, perform a logical AND on them.
or      Pop the top two numbers, perform a logical OR on them.
not     Pop the top two numbers, perform a logical NOT on them.

*note: When performing logic operations, any number non 0 is considered
       true.  When operations push results, 1 is used for true.
</code></pre>

<h4>IO</h4>

<pre><code>output       Pop the top number and print it to stdout followed by a space.
outputascii  Pop the top number and print it to stdout as an ascii
             character.
input        Prompt the user to enter a number and push it onto the stack.
inputascii   This one's a bit confusing.  Allow the user to input a string 
             and push the ascii values of each character in reverse onto 
             the stack.  See Command Examples for more information.
</code></pre>

<h4>Misc</h4>

<pre><code>random  Pop the top number, and generate a random number between 0 and
        1 less than the popped number.  See Command Examples for more info.
debug   Output the entire stack to stdout.
quit    Terminate the program.
</code></pre>

<h3>Command Examples</h3>

<h4>Using inputascii</h4>

<p><code>inputascii</code> pushes the inputed string in reverse onto the stack.  So if the 
command was run and the user inputted <code>"abc"</code>, the stack would be:</p>

<pre><code>[99, 98, 97]
</code></pre>

<p>or when looking at the values as ascii characters:</p>

<pre><code>[c, b, a]
</code></pre>

<p>This is done intentionally so the programmer will have access to the first
character first, second character second, etc.</p>

<h3>Libraries</h3>
